How It Works
Every hour, a background sync job checks for new tax-related updates across supported countries and jurisdictions. These updates are queued, validated, and then automatically applied within the system — including country, jurisdiction, and county-level rules.Update Structure
Each tax update is stored and processed based on a standardized structure:| Field | Description |
|---|---|
UpdateID | Unique identifier for the update event |
ExecutionDate | Scheduled execution date (in UTC) |
ExecutionTime | Timestamp (in ms) for when execution will occur |
TimeZone | Timezone offset (in minutes) for the jurisdiction |
TypeOfUpdate | Create New or Update Existing |
TypeOfField | Field being modified — Standard Rate, Special Rate, or Additional Taxes |
OldValue | JSON object storing the previous value |
NewValue | JSON object storing the new value |
ProductCategories | List of internal category IDs affected by this update |
ProductDeliveryMethods | Delivery method types affected (e.g., CLOUD, PHYSICAL) |
CustomerType | Array of customer types the rule applies to (e.g., B2B, B2C) |
CountryID | Internal reference to the affected country |
JurisdictionID | One or more jurisdiction references affected |
CountyID | Optional — applies if county-specific overrides exist |
Execution Lifecycle
Each update follows a structured lifecycle:| Status | Description |
|---|---|
Not Started | Update is registered but not yet queued for execution |
In Process | The update is currently being applied to the system |
Completed | Successfully executed and reflected in live tax APIs |
Error | Logged for review if execution fails — retried automatically with backoff |
StartTime, EndTime, and ProcessingTime to ensure transparency and operational monitoring.
Auditability & Governance
- All updates are stored immutably with timestamps.
- Audit logs record changes at the field level.
- Failures are isolated and do not affect system availability.
- Rollbacks are supported in the rare event of downstream impact.
Use Cases
- Jurisdiction introduces a new digital services tax
- Country increases standard VAT rate
- Special tax holiday applied at county level
- Regulatory notice affecting B2B exemptions